//----------------------------------*-C++-*----------------------------------//
/*!
 * \file   styleguide.hh
 * \author Jeremy Roberts
 * \date   Jul 13, 2011
 * \brief  an overview of style used in SLABTRAN
 * \note   Copyright (C) 2011 Jeremy Roberts. 
 */
//---------------------------------------------------------------------------//
// $Rev::                                               $:Rev of last commit
// $Author:: j.alyn.roberts@gmail.com                   $:Author of last commit
// $Date::                                              $:Date of last commit
//---------------------------------------------------------------------------//


#ifndef STYLEGUIDE_HH_
#define STYLEGUIDE_HH_

/*!
 * \page StyleGuide StyleGuide
 *
 * In writing this code, the key objective with respect to style is to <em> be
 * consistent </em>.
 *
 * This is helped in part by developing in Eclipse, which has a formatting
 * function with built-in templates that can be modified.  The following
 * is a brief list of key style aspects we have tried to use consistently.
 * Deviations can be purposeful (and it should be obvious why); otherwise,
 * deviations should be corrected.
 *
 * Style aspects:
 * - Braces start on the next line, e.g.
 *    \code
 *      void foo()
 *      {
 *        \\ do something
 *      }
 *    \endcode
 * - Indentation is by two spaces in general, and by column for argument lists
 *    and similar constructs
 * - Lines should be 80 lines or less for readability.  Line breaks should
 *    be sensibly made.
 * - Class methods are documented in the header and take the form
 *    \code
 *      \*! (forward slash, not back slash in real comment)
 *      *  \brief  a brief description of MyClassMethod.
 *      *
 *      *  A longer description of my_class_method.
 *      *
 *      *  \param       parameter   description of my parameter
 *      *  \return                  description of what I return
 *      *\/  (omit back slash in real comment)
 *      int MyClass::my_class_method(int parameter);
 *    \endcode
 * - naming:
 *  - Naming for classes and methods: right now it's ugly, but mostly
 *    classes are in CamelCase with a good number using underscores as
 *    in Camel_Case.  Most of these are modified versions of Denovo
 *    classes and should be renamed to fit the CamelCase style.
 *  - Methods should be given a sensible name using lower case and for
 *    multiple words, underscores should be used.
 *  - Member variables take the form \em d_variable.  The "d" was borrowed
 *     from Denovo style, but there it actually denotes "derived" whereas
 *     base classes have "b".  Here, we use "d" for everything.  If it makes
 *     you feel better, use "d" for class private "data".  In any case, such
 *     a prefix form \em d_variable is IMHO \em way better looking than
 *     the trailing underscore, e.g. \em variable_.
 *  - An accessor for \em d_variable should be named \em variable().
 *  - Typedefs typically follow the class naming convention.
 *    Those typedefs that make a short definition for a class should
 *    be named like a class.  Typedefs of smart pointers to classes
 *    take the form \em SP_classname.
 *
 *
 *  \todo correct broken style when encountered!!
 *  \todo change class/file names from caps with underscore to CamelCase for consistency.
 *
 */


#endif /* STYLEGUIDE_HH_ */

//---------------------------------------------------------------------------//
//              end of styleguide.hh
//---------------------------------------------------------------------------//
